OpenSpec + Antigravity CLI 規範樣板手冊

本手冊定義了新專案如何透過 Antigravity CLI 與 OpenSpec 進行「規格驅動開發 (Spec-driven Development)」，確保 AI 代理在撰寫程式碼時，嚴格遵循版控、規格同步與防呆機制。

0. 核心觀念：這些隱藏目錄是怎麼來的？

在開始複製樣板前，我們必須先理解專案根目錄下最重要的兩個資料夾：.agent 與 openspec 的由來與定位：

🧠 `.agent` 是怎麼來的？(AI 的大腦設定)

由來：這是 Google Antigravity (AGY) AI 原生支援的「工作區客製化 (Workspace Customizations)」機制。
作用：Antigravity CLI 在每次啟動或讀取專案時，會主動尋找 .agent 資料夾。我們可以把它當作是「給 AI 吃的特殊維他命」。透過裡面的 AGENTS.md (鐵律) 以及 skills (客製化技能)，我們能直接修改 AI 的預設行為，讓它從一個「通用的打字機」變成「完全懂你專案龜毛要求的資深工程師」。

📐 `openspec` 目錄是怎麼來的？(專案規格的資料庫)

由來：這是由 OpenSpec 這個架構/技能體系所建立的資料夾。通常是透過 AI 執行 openspec init，或由我們依照本手冊手動建立。
作用：它不包含專案的程式碼 (Source Code)，而是專案的「規格書與任務單 (Source of Truth)」。透過 .agent 裡安裝的指令，AI 會將使用者的需求，轉化為 openspec/ 目錄下的文件。AI 在寫 Code 前，都會先來這個目錄看「計畫是什麼？」，避免偏離軌道。

💡 簡單總結：
- .agent/ 決定 AI 「怎麼做事」（遵守鐵律、執行前詢問）。
- openspec/ 決定 AI 「要做什麼事」（讀取規格、確認任務）。

1. 📂 專案基礎目錄結構 (Directory Structure)

啟動新專案時，請確保建立以下目錄結構，讓「大腦」與「規格資料庫」就位：

my-new-project/
├── .agent/                  # 【AI 行為控制中心】
│   ├── AGENTS.md            # 專案鐵律 (防呆、版控、介面等實作細節規範)
│   ├── skills/              # 客製化技能 (從全域或舊專案複製過來)
│   └── workflows/           # 專屬工作流
├── openspec/                # 【規格驅動開發大腦】
│   ├── config.yaml          # OpenSpec 設定檔 (控制 AI 產出規格的語言與前提)
│   ├── specs/               # 系統主文件與規格
│   └── changes/             # 開發中的變更提案與任務
└── ... (其他專案原始碼)

2. 📝 專案鐵律樣板 (`.agent/AGENTS.md`)

請在新專案下建立 .agent/AGENTS.md 並貼上以下內容。這些是不可侵犯的底線，能有效防止 AI 暴走或破壞專案結構：

# 專案鐵律 (Rules)

- **執行前確認 (Execution Confirmation)**：在修改檔案、執行指令或進行其他破壞性變更之前，永遠必須先向使用者提出計畫與變更內容，並取得明確同意後才可執行。
- **嚴格的版本控制 (Strict Version Control)**：在完成任何重大更新或功能後，永遠必須主動執行 `git add .` 與 `git commit` 以確保擁有完整的版本歷史紀錄。
- **非同步任務同步 (Async Task Synchronization)**：當呼叫非同步的背景子代理或任務時（例如同步 specs），永遠必須等待子代理回傳完成訊息後，才可進行最後的 Git Commit 或分支操作。
- **防呆與錯誤處理 (Error Handling & Guardrails)**：在實作任何核心邏輯或 UI 互動時，必須主動考慮極端情況 (Edge cases)，並加入適當的警告、日誌或 UI 阻擋機制。
- **流程圖文件化 (Flowchart Documentation - Spec)**：在對話過程中產生的任何系統架構、狀態機或邏輯流程圖，都必須使用 `mermaid` 語法記錄到對應的 Spec (Markdown) 文件中。
- **自動同步主文件 (Auto-Sync Master Docs)**：每當變更被歸檔 (Archived) 且規格更新後，絕對必須自動重新生成 `openspec/specs/README.md` 以及架構總覽文件，以反映最新的系統架構、能力與資料模型。
- **[選用] 強制多國語系翻譯 (Mandatory I18n Translation)**：每當新增或修改 UI 上的文字元素時，絕對必須在字典檔中為所有支援的語言提供對應的翻譯，不可直接將字串寫死在 HTML 中。

3. ⚙️ OpenSpec 專案設定檔 (`openspec/config.yaml`)

這是讓 AI 在撰寫計畫時（例如執行 /openspec-propose 時）能自動進入狀況的關鍵設定。請建立 openspec/config.yaml 並根據新專案微調：

schema: spec-driven

# 專案背景知識 (Project Context)
# 在建立 proposal, tasks, specs 時，AI 會自動讀取這裡的資訊。
context: |
  Project: [請填寫新專案名稱] (例如：智慧工廠 Web Dashboard)
  Tech Stack: [請填寫技術棧] (例如：Node.js, Vue3, SQLite)
  Conventions:
    - 遵守 Conventional Commits 規範 (例如：feat:, fix:, chore:)
    - 嚴格遵守 Spec-driven (規格驅動) 的開發流程
  Language Requirement:
    - CRITICAL: 所有未來產出的 OpenSpec 文件 (包含提案、任務與規格) **絕對必須** 使用繁體中文 (zh-TW) 撰寫。

# 針對各個產出物的個別限制 (Per-artifact rules)
rules:
  proposal:
    - "Must be written in Traditional Chinese (zh-TW) / 所有提案必須以繁體中文撰寫"
  tasks:
    - "Must be written in Traditional Chinese (zh-TW) / 所有任務必須以繁體中文撰寫"
  specs:
    - "Must be written in Traditional Chinese (zh-TW) / 所有規格說明書必須以繁體中文撰寫"

4. 🙈 版本控制忽略清單樣板 (`.gitignore`)

建議在新專案一開始就建立 .gitignore 檔案，避免不必要的大型檔案或隱私資訊進入版本控制。您可以根據專案需求複製以下通用範本：

venv/
node_modules/
__pycache__/
*.pyc
.DS_Store
.env
logs/
records/
*.db
*.log
*.csv

5. 🚀 快速啟動檢核表 (Quick Start Checklist)

未來拿到任何新專案，只要跟著以下步驟走：

[ ] 建立專案目錄並進入：在終端機執行 mkdir my-new-project，然後 cd my-new-project。

[ ] 初始化版本控制：請先建立 .gitignore 檔案並貼上上述範本。接著，在命令列複製執行以下指令，完成身份確認與首次 Commit：

# 確保已設定全域名稱與信箱 (若已設定過可略過這兩行)
git config --global user.name "您的名字"
git config --global user.email "您的信箱"

# 初始化並進行首次提交
git init
git add .gitignore
git commit -m "chore: initial commit with gitignore"

[ ] 產生專屬大腦結構：執行 openspec init。系統會自動在當前目錄下產生專屬的 .agent 與 openspec 資料夾。
[ ] 啟動 AI 並切換模型：執行 agy init 啟動 Antigravity CLI，務必先將模型切換為 pro (High) 以獲得最佳的邏輯推理能力。（操作方式：在對話框輸入 /model 然後選擇 pro，或直接輸入 /model pro）

[ ] 注入鐵律與設定：將本手冊中的規範寫入專案中。您有兩種選擇：

方案 A (自行建立)：手動將本手冊中建議的 AGENTS.md 與 config.yaml 複製並覆蓋進去。

方案 B (請 AI 建立)：在 CLI 中直接貼上以下完整指令，讓 AI 一次幫您建好兩個檔案：

請幫我建立新專案的基礎規範。

1. 請寫入以下內容到 `.agent/AGENTS.md` 檔案中：
# 專案鐵律 (Rules)
- **執行前確認 (Execution Confirmation)**：在修改檔案、執行指令或進行破壞性變更之前，永遠必須先向使用者提出計畫與變更內容，並取得明確同意後才可執行。
- **嚴格的版本控制 (Strict Version Control)**：在完成任何重大更新或功能後，永遠必須主動執行 `git add .` 與 `git commit`。
- **非同步任務同步 (Async Task Synchronization)**：當呼叫非同步的背景子代理或任務時，永遠必須等待回傳完成訊息後，才可進行 Git Commit 或分支操作。
- **防呆與錯誤處理 (Error Handling & Guardrails)**：在實作任何核心邏輯或 UI 互動時，必須主動考慮極端情況並加入適當的阻擋機制。
- **流程圖文件化 (Flowchart Documentation)**：產生的系統架構或邏輯流程圖，必須使用 `mermaid` 語法記錄到 Spec 文件中。
- **自動同步主文件 (Auto-Sync Master Docs)**：變更歸檔後，必須自動重新生成 `openspec/specs/README.md`。

2. 請寫入以下內容到 `openspec/config.yaml` 檔案中：
schema: spec-driven
context: |
  Project: [填寫專案名稱]
  Tech Stack: [填寫技術棧]
  Conventions:
    - 遵守 Conventional Commits 規範
    - 嚴格遵守 Spec-driven 的開發流程
  Language Requirement:
    - CRITICAL: 所有未來產出的 OpenSpec 文件絕對必須使用繁體中文 (zh-TW) 撰寫。
rules:
  proposal:
    - "Must be written in Traditional Chinese (zh-TW) / 所有提案必須以繁體中文撰寫"
  tasks:
    - "Must be written in Traditional Chinese (zh-TW) / 所有任務必須以繁體中文撰寫"
  specs:
    - "Must be written in Traditional Chinese (zh-TW) / 所有規格說明書必須以繁體中文撰寫"

完成後請告訴我。

[ ] 開始協作：設定完成後，即可開始對話（例如：「請遵守 .agent/AGENTS.md 的鐵律，並使用 /openspec-propose 幫我建立專案的第一個提案。」）。
- 💡 如何接續對話？：如果您使用 Ctrl+D 離開 Antigravity CLI，日後只要再次執行 agy init，接著輸入 /resume 即可列出歷史對話；輸入對應的短 ID（例如 /resume <短ID>）就能直接恢復先前的記憶與工作狀態。

文件基於工具版本：openspec 1.5.0，agy 1.0.15

OpenSpec + Antigravity CLI 規範樣板手冊

0. 核心觀念：這些隱藏目錄是怎麼來的？

🧠 .agent 是怎麼來的？(AI 的大腦設定)

📐 openspec 目錄是怎麼來的？(專案規格的資料庫)